home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 17 / CU Amiga Magazine's Super CD-ROM 17 (1997)(EMAP Images)(GB)[!][issue 1997-12].iso / CUCD / Programming / DiceSource / src / alib / csup / intuition_support / autodocs.asm next >
Assembly Source File  |  1994-02-14  |  12KB  |  406 lines
  1. ******* amiga.lib/CallHook ***************************************************
  2. *
  3. *   NAME
  4. *    CallHook -- Invoke a hook given a message on the stack.
  5. *
  6. *   SYNOPSIS
  7. *    result = CallHook( hookPtr, obj, ... )
  8. *
  9. *    ULONG CallHook( struct Hook *, Object *, ... );
  10. *
  11. *   FUNCTION
  12. *    Like CallHookA(), CallHook() invoke a hook on the supplied
  13. *    hook-specific data (an "object") and a parameter packet ("message").
  14. *    However, CallHook() allows you to build the message on your stack.
  15. *
  16. *   INPUTS
  17. *    hookPtr - A system-standard hook
  18. *    obj - hook-specific data object
  19. *    ... - The hook-specific message you wish to send.  The hook is
  20. *        expecting a pointer to the message, so a pointer into your
  21. *        stack will be sent.
  22. *
  23. *   RESULT
  24. *    result - a hook-specific result.
  25. *
  26. *   NOTES
  27. *    This function first appeared in the V37 release of amiga.lib.
  28. *    However, it does not depend on any particular version of the OS,
  29. *    and works fine even in V34.
  30. *
  31. *   EXAMPLE
  32. *    If your hook's message was
  33. *
  34. *        struct myMessage
  35. *        {
  36. *        ULONG mm_FirstGuy;
  37. *        ULONG mm_SecondGuy;
  38. *        ULONG mm_ThirdGuy;
  39. *        };
  40. *
  41. *    You could write:
  42. *
  43. *        result = CallHook( hook, obj, firstguy, secondguy, thirdguy );
  44. *
  45. *    as a shorthand for:
  46. *
  47. *        struct myMessage msg;
  48. *
  49. *        msg.mm_FirstGuy = firstguy;
  50. *        msg.mm_SecondGuy = secondguy;
  51. *        msg.mm_ThirdGuy = thirdguy;
  52. *
  53. *        result = CallHookA( hook, obj, &msg );
  54. *
  55. *   SEE ALSO
  56. *    CallHookA(), utility.library/CallHookPkt(), <utility/hooks.h>
  57. *
  58. ******************************************************************************
  59.  
  60. ******* amiga.lib/CallHookA **************************************************
  61. *
  62. *   NAME
  63. *    CallHookA -- Invoke a hook given a pointer to a message.
  64. *
  65. *   SYNOPSIS
  66. *    result = CallHookA( hookPtr, obj, message )
  67. *
  68. *    ULONG CallHook( struct Hook *, Object *, APTR );
  69. *
  70. *   FUNCTION
  71. *    Invoke a hook on the supplied hook-specific data (an "object")
  72. *    and a parameter packet ("message").  This function is equivalent
  73. *    to utility.library/CallHookPkt().
  74. *
  75. *   INPUTS
  76. *    hookPtr - A system-standard hook
  77. *    obj - hook-specific data object
  78. *    message - The hook-specific message you wish to send
  79. *
  80. *   RESULT
  81. *    result - a hook-specific result.
  82. *
  83. *   NOTES
  84. *    This function first appeared in the V37 release of amiga.lib.
  85. *    However, it does not depend on any particular version of the OS,
  86. *    and works fine even in V34.
  87. *
  88. *   SEE ALSO
  89. *    CallHook(), utility.library/CallHookPkt(), <utility/hooks.h>
  90. *
  91. ******************************************************************************
  92.  
  93. ******* amiga.lib/HookEntry **************************************************
  94. *
  95. *   NAME
  96. *    HookEntry -- Assembler to HLL conversion stub for hook entry.
  97. *
  98. *   SYNOPSIS
  99. *    result = HookEntry( struct Hook *, Object *, APTR )
  100. *    D0                  A0             A2        A1
  101. *
  102. *   FUNCTION
  103. *    By definition, a standard hook entry-point must receive the
  104. *    hook in A0, the object in A2, and the message in A1.  If your
  105. *    hook entry-point is written in a high-level language and is
  106. *    expecting its parameters on the stack, then HookEntry() will
  107. *    put the three parameters on the stack and invoke the function
  108. *    stored in the hook h_SubEntry field.
  109. *
  110. *    This function is only useful to hook implementers, and is
  111. *    never called from C.
  112. *
  113. *   INPUTS
  114. *    hook - pointer to hook being invoked
  115. *    object - pointer to hook-specific data
  116. *    msg - pointer to hook-specific message
  117. *
  118. *   RESULT
  119. *    result - a hook-specific result.
  120. *
  121. *   NOTES
  122. *    This function first appeared in the V37 release of amiga.lib.
  123. *    However, it does not depend on any particular version of the OS,
  124. *    and works fine even in V34.
  125. *
  126. *   EXAMPLE
  127. *    If your hook dispatcher is this:
  128. *
  129. *    dispatch( struct Hook *hookPtr, Object *obj, APTR msg )
  130. *    {
  131. *        ...
  132. *    }
  133. *
  134. *    Then when you initialize your hook, you would say:
  135. *
  136. *    myhook.h_Entry = HookEntry;    /* amiga.lib stub */
  137. *    myhook.h_SubEntry = dispatch;    /* HLL entry */
  138. *
  139. *   SEE ALSO
  140. *    CallHook(), CallHookA(), <utility/hooks.h>
  141. *    
  142. ******************************************************************************
  143.  
  144. ******* amiga.lib/DoMethodA **************************************************
  145. *
  146. *   NAME
  147. *    DoMethodA -- Perform method on object.
  148. *
  149. *   SYNOPSIS
  150. *    result = DoMethodA( obj, msg )
  151. *
  152. *    ULONG DoMethodA( Object *, Msg );
  153. *
  154. *   FUNCTION
  155. *    Boopsi support function that invokes the supplied message
  156. *    on the specified object.  The message is invoked on the
  157. *    object's true class.
  158. *
  159. *   INPUTS
  160. *    obj - pointer to boopsi object
  161. *    msg - pointer to method-specific message to send
  162. *
  163. *   RESULT
  164. *    result - specific to the message and the object's class.
  165. *
  166. *   NOTES
  167. *    This function first appears in the V37 release of amiga.lib.
  168. *    While it intrinsically does not require any particular release
  169. *    of the system software to operate, it is designed to work with
  170. *    the boopsi subsystem of Intuition, which was only introduced
  171. *    in V36.
  172. *    Some early example code may refer to this function as DM().
  173. *
  174. *   SEE ALSO
  175. *    DoMethod(), CoerceMethodA(), DoSuperMethodA(), <intuition/classusr.h>
  176. *    ROM Kernel Manual boopsi section
  177. *
  178. ******************************************************************************
  179.  
  180. ******* amiga.lib/DoMethod ***************************************************
  181. *
  182. *   NAME
  183. *    DoMethod -- Perform method on object.
  184. *
  185. *   SYNOPSIS
  186. *    result = DoMethod( obj, MethodID, ... )
  187. *
  188. *    ULONG DoMethod( Object *, ULONG, ... );
  189. *
  190. *   FUNCTION
  191. *    Boopsi support function that invokes the supplied message
  192. *    on the specified object.  The message is invoked on the
  193. *    object's true class.  Equivalent to DoMethodA(), but allows
  194. *    you to build the message on the stack.
  195. *
  196. *   INPUTS
  197. *    obj - pointer to boopsi object
  198. *    MethodID - which method to send (see <intuition/classusr.h>)
  199. *    ... - method-specific message built on the stack
  200. *
  201. *   RESULT
  202. *    result - specific to the message and the object's class.
  203. *
  204. *   NOTES
  205. *    This function first appears in the V37 release of amiga.lib.
  206. *    While it intrinsically does not require any particular release
  207. *    of the system software to operate, it is designed to work with
  208. *    the boopsi subsystem of Intuition, which was only introduced
  209. *    in V36.
  210. *
  211. *   SEE ALSO
  212. *    DoMethodA(), CoerceMethodA(), DoSuperMethodA(), <intuition/classusr.h>
  213. *    ROM Kernel Manual boopsi section
  214. *
  215. ******************************************************************************
  216.  
  217. ******* amiga.lib/CoerceMethodA *********************************************************
  218. *
  219. *   NAME
  220. *    CoerceMethodA -- Perform method on coerced object.
  221. *
  222. *   SYNOPSIS
  223. *    result = CoerceMethodA( cl, obj, msg )
  224. *
  225. *    ULONG CoerceMethodA( struct IClass *, Object *, Msg );
  226. *
  227. *   FUNCTION
  228. *    Boopsi support function that invokes the supplied message
  229. *    on the specified object, as though it were the specified
  230. *    class.
  231. *
  232. *   INPUTS
  233. *    cl - pointer to boopsi class to receive the message
  234. *    obj - pointer to boopsi object
  235. *    msg - pointer to method-specific message to send
  236. *
  237. *   RESULT
  238. *    result - class and message-specific result.
  239. *
  240. *   NOTES
  241. *    This function first appears in the V37 release of amiga.lib.
  242. *    While it intrinsically does not require any particular release
  243. *    of the system software to operate, it is designed to work with
  244. *    the boopsi subsystem of Intuition, which was only introduced
  245. *    in V36.
  246. *    Some early example code may refer to this function as CM().
  247. *
  248. *   SEE ALSO
  249. *    CoerceMethod(), DoMethodA(), DoSuperMethodA(), <intuition/classusr.h>
  250. *    ROM Kernel Manual boopsi section
  251. *
  252. ******************************************************************************
  253.  
  254. ******* amiga.lib/CoerceMethod ***********************************************
  255. *
  256. *   NAME
  257. *    CoerceMethod -- Perform method on coerced object.
  258. *
  259. *   SYNOPSIS
  260. *    result = CoerceMethod( cl, obj, MethodID, ... )
  261. *
  262. *    ULONG CoerceMethod( struct IClass *, Object *, ULONG, ... );
  263. *
  264. *   FUNCTION
  265. *    Boopsi support function that invokes the supplied message
  266. *    on the specified object, as though it were the specified
  267. *    class.  Equivalent to CoerceMethodA(), but allows you to
  268. *    build the message on the stack.
  269. *
  270. *   INPUTS
  271. *    cl - pointer to boopsi class to receive the message
  272. *    obj - pointer to boopsi object
  273. *    ... - method-specific message built on the stack
  274. *
  275. *   RESULT
  276. *    result - class and message-specific result.
  277. *
  278. *   NOTES
  279. *    This function first appears in the V37 release of amiga.lib.
  280. *    While it intrinsically does not require any particular release
  281. *    of the system software to operate, it is designed to work with
  282. *    the boopsi subsystem of Intuition, which was only introduced
  283. *    in V36.
  284. *
  285. *   SEE ALSO
  286. *    CoerceMethodA(), DoMethodA(), DoSuperMethodA(), <intuition/classusr.h>
  287. *    ROM Kernel Manual boopsi section
  288. *
  289. ******************************************************************************
  290.  
  291. ******* amiga.lib/DoSuperMethodA *********************************************
  292. *
  293. *   NAME
  294. *    DoSuperMethodA -- Perform method on object coerced to superclass.
  295. *
  296. *   SYNOPSIS
  297. *    result = DoSuperMethodA( cl, obj, msg )
  298. *
  299. *    ULONG DoSuperMethodA( struct IClass *, Object *, Msg );
  300. *
  301. *   FUNCTION
  302. *    Boopsi support function that invokes the supplied message
  303. *    on the specified object, as though it were the superclass
  304. *    of the specified class.
  305. *
  306. *   INPUTS
  307. *    cl - pointer to boopsi class whose superclass is to
  308. *        receive the message
  309. *    obj - pointer to boopsi object
  310. *    msg - pointer to method-specific message to send
  311. *
  312. *   RESULT
  313. *    result - class and message-specific result.
  314. *
  315. *   NOTES
  316. *    This function first appears in the V37 release of amiga.lib.
  317. *    While it intrinsically does not require any particular release
  318. *    of the system software to operate, it is designed to work with
  319. *    the boopsi subsystem of Intuition, which was only introduced
  320. *    in V36.
  321. *    Some early example code may refer to this function as DSM().
  322. *
  323. *   SEE ALSO
  324. *    CoerceMethodA(), DoMethodA(), DoSuperMethod(), <intuition/classusr.h>
  325. *    ROM Kernel Manual boopsi section
  326. *
  327. ******************************************************************************
  328.  
  329. ******* amiga.lib/DoSuperMethod **********************************************
  330. *
  331. *   NAME
  332. *    DoSuperMethod -- Perform method on object coerced to superclass.
  333. *
  334. *   SYNOPSIS
  335. *    result = DoSuperMethod( cl, obj, MethodID, ... )
  336. *
  337. *    ULONG DoSuperMethod( struct IClass *, Object *, ULONG, ... );
  338. *
  339. *   FUNCTION
  340. *    Boopsi support function that invokes the supplied message
  341. *    on the specified object, as though it were the superclass
  342. *    of the specified class.  Equivalent to DoSuperMethodA(),
  343. *    but allows you to build the message on the stack.
  344. *
  345. *   INPUTS
  346. *    cl - pointer to boopsi class whose superclass is to
  347. *        receive the message
  348. *    obj - pointer to boopsi object
  349. *    ... - method-specific message built on the stack
  350. *
  351. *   RESULT
  352. *    result - class and message-specific result.
  353. *
  354. *   NOTES
  355. *    This function first appears in the V37 release of amiga.lib.
  356. *    While it intrinsically does not require any particular release
  357. *    of the system software to operate, it is designed to work with
  358. *    the boopsi subsystem of Intuition, which was only introduced
  359. *    in V36.
  360. *
  361. *   SEE ALSO
  362. *    CoerceMethodA(), DoMethodA(), DoSuperMethodA(), <intuition/classusr.h>
  363. *    ROM Kernel Manual boopsi section
  364. *
  365. ******************************************************************************
  366.  
  367. ******* amiga.lib/SetSuperAttrs **********************************************
  368. *
  369. *   NAME
  370. *    SetSuperAttrs -- Invoke OM_SET method on superclass with varargs.
  371. *
  372. *   SYNOPSIS
  373. *    result = SetSuperAttrs( cl, obj, tag, ... )
  374. *
  375. *    ULONG SetSuperAttrs( struct IClass *, Object *, ULONG, ... );
  376. *
  377. *   FUNCTION
  378. *    Boopsi support function which invokes the OM_SET method on the
  379. *    superclass of the supplied class for the supplied object.  Allows
  380. *    the ops_AttrList to be supplied on the stack (i.e. in a varargs
  381. *    way).  The equivalent non-varargs function would simply be
  382. *
  383. *        DoSuperMethod( cl, obj, OM_SET, taglist, NULL );
  384. *
  385. *   INPUTS
  386. *    cl - pointer to boopsi class whose superclass is to
  387. *        receive the OM_SET message
  388. *    obj - pointer to boopsi object
  389. *    tag - list of tag-attribute pairs, ending in TAG_DONE
  390. *
  391. *   RESULT
  392. *    result - class and message-specific result.
  393. *
  394. *   NOTES
  395. *    This function first appears in the V37 release of amiga.lib.
  396. *    While it intrinsically does not require any particular release
  397. *    of the system software to operate, it is designed to work with
  398. *    the boopsi subsystem of Intuition, which was only introduced
  399. *    in V36.
  400. *
  401. *   SEE ALSO
  402. *    CoerceMethodA(), DoMethodA(), DoSuperMethodA(), <intuition/classusr.h>
  403. *    ROM Kernel Manual boopsi section
  404. *
  405. ******************************************************************************
  406.